<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>libnetconf: Transport Protocol</title>
<link href="../../tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../jquery.js"></script>
<script type="text/javascript" src="../../dynsections.js"></script>
<link href="../../navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../resize.js"></script>
<script type="text/javascript" src="../../navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="../../search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="../../doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="../../libnetconf-logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">libnetconf
   &#160;<span id="projectnumber">0.10.0-146_trunk</span>
   </div>
   <div id="projectbrief">NETCONF Library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "../../search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="../../index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="../../pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="../../modules.html"><span>Modules</span></a></li>
      <li><a href="../../annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="../../files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="../../search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="../../search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('d4/d76/transport.html','../../');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Transport Protocol </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>NETCONF protocol specifies the set of requirements for the transport protocol in <a href="http://tools.ietf.org/html/rfc6241" title="RFC 6241">RFC 6241</a>. There are currently 2 specifications how to use specific transport protocols for NETCONF: [RFC 6242][RFC6242] for Secure SHell (SSH) and <a href="http://tools.ietf.org/html/draft-ietf-netconf-rfc5539bis-05" title="RFC 5539bis">RFC 5539bis</a> for Transport Layer Security (TLS). SSH is mandatory transport for NETCONF implementations.</p>
<p>libnetconf supports SSH transport out of the box. From version 0.8, there is also experimental support for TLS transport. By default, this is not available by default. To enable TLS transport, following action must be performed:</p>
<ul>
<li>run configure with <code>--enable-tls</code> option: <div class="fragment"><div class="line">./configure --enable-tls</div>
</div><!-- fragment --></li>
</ul>
<p>See the <a href="https://code.google.com/p/netopeer/" title="Netopeer">Netopeer project</a> as a reference implementation.</p>
<h1><a class="anchor" id="transport-client"></a>
Transport Support on the Client Side</h1>
<p>To switch from the default SSH transport to the TLS transport, application must call <a class="el" href="../../db/d52/group__session.html#ga6e125c035cdebae8c49ff962866c0806" title="Set transport protocol for the sessions created by subsequent nc_session_connect() calls...">nc_session_transport()</a> with <a class="el" href="../../db/d52/group__session.html#gga8be6ccea205129b05c38331a7a42174aa9dfde07fbf3ce02396167716ef70c612">NC_TRANSPORT_TLS</a> parameter. Remember, that this change applies only to the current thread.</p>
<p>Next step is to initiate TLS context for the new NETCONF session. Using <a class="el" href="../../db/db4/group__tls.html#gacbf946a826fa6c7c18a4e66d532b659f" title="Set paths to the client certificate and its private key. ">nc_tls_init()</a> function, client is supposed to set its client certificate and CA for server certificate validation.</p>
<p>Now the TLS context is ready and new NETCONF session over TLS can be established using <a class="el" href="../../db/d52/group__session.html#gae3858d998d19cb2fb700b15fdf602f23" title="Create NETCONF session to the specified server. ">nc_session_connect()</a>. Application can run <a class="el" href="../../db/db4/group__tls.html#gacbf946a826fa6c7c18a4e66d532b659f" title="Set paths to the client certificate and its private key. ">nc_tls_init()</a> again, but the changed parameters will be applied only to the newly created NETCONF sessions.</p>
<p>To properly clean all resources, call <a class="el" href="../../db/db4/group__tls.html#gacf3aed5cccac55d0548f46761707ece9" title="Destroy all resources allocated for preparation of TLS connections. ">nc_tls_destroy()</a>. It will destroy TLS connection context. This function can be called despite the running NETCONF session, but creating a new NETCONF session over TLS is not allowed after calling <a class="el" href="../../db/db4/group__tls.html#gacf3aed5cccac55d0548f46761707ece9" title="Destroy all resources allocated for preparation of TLS connections. ">nc_tls_destroy()</a> - the client has to call <a class="el" href="../../db/db4/group__tls.html#gacbf946a826fa6c7c18a4e66d532b659f" title="Set paths to the client certificate and its private key. ">nc_tls_init()</a> again.</p>
<p>The whole process described here is supposed to be performed in a single thread. SSH transport works out of the box, so no specific step, as mentioned for TLS in this section, is required.</p>
<h1><a class="anchor" id="transport-server"></a>
Transport Support on the Server Side</h1>
<p>There is no specific support for neither SSH or TLS on the server side. libnetconf doesn't implement SSH nor TLS server - it is expected, that NETCONF server application uses external application (sshd, stunnel,...) serving as SSH/TLS server and providing NETCONF data to the NETCONF server stdin, where libnetconf can read the data, and getting data from the NETCONF server stdout to encapsulate the data and send to a client.</p>
<p>For both cases, SSH as well as TLS, there are two functions: <a class="el" href="../../db/d52/group__session.html#gad0e758dfee764ae9c2a032e0151c6707" title="Accept NETCONF session from a client. ">nc_session_accept()</a> and <a class="el" href="../../db/d52/group__session.html#ga7ee207cac84fd5cd82419af41e14c06f" title="Accept NETCONF session from a client and assign it to the specified username. ">nc_session_accept_username()</a>, that serve to accept incoming connection despite the transport protocol. As mentioned, they read data from stdin and write data to the stdout. Difference between those functions is in recognizing NETCONF username. <a class="el" href="../../db/d52/group__session.html#gad0e758dfee764ae9c2a032e0151c6707" title="Accept NETCONF session from a client. ">nc_session_accept()</a> guesses username from the process's UID. For example, in case of using SSH Subsystem mechanism in OpenSSH implementation, SSH daemon automatically changes UID of the launched SSH Subsystem process (NETCONF server/agent) to the UID of the logged user. But in case of other SSH/TLS server, this doesn't have to be done. In such a case, NETCONF server itself is supposed to correctly recognize the NETCONF username and specify it explicitly when establishing NETCONF session using <a class="el" href="../../db/d52/group__session.html#ga7ee207cac84fd5cd82419af41e14c06f" title="Accept NETCONF session from a client and assign it to the specified username. ">nc_session_accept_username()</a>. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="../../da/d1b/usage.html">Using libnetconf</a></li>
    <li class="footer">Generated on Fri Apr 15 2016 09:20:09 for libnetconf by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="../../doxygen.png" alt="doxygen"/></a> 1.8.6 </li>
  </ul>
</div>
</body>
</html>
